home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / ref / postquel / defineoperator < prev    next >
Encoding:
Text File  |  1992-08-27  |  7.6 KB  |  281 lines
  1. .\" XXX standard disclaimer belongs here....
  2. .\" $Header: /private/postgres/ref/postquel/RCS/defineoperator,v 1.10 1992/07/14 05:54:17 ptong Exp $
  3. .SP "DEFINE OPERATOR" COMMANDS 6/14/90
  4. .XA 2 "Define Operator"
  5. .uh NAME
  6. .lp
  7. define operator \*- define a new user operator
  8. .uh SYNOPSIS
  9. .lp
  10. .(l
  11. \fBdefine operator\fR operator_name
  12.     \fB(\fR \fBarg1\fR \fB=\fR type-1
  13.      [ \fB,\fR \fBarg2\fR \fB=\fR type-2 ]
  14.      , \fBprocedure =\fR func_name
  15.      [\fB, precedence =\fR number ]
  16.      [\fB, associativity =\fR \fB(left | right | none | any)\fR ]
  17.      [\fB, commutator =\fR com_op ]
  18.      [\fB, negator =\fR neg_op ]
  19.      [\fB, restrict =\fR res_proc ]
  20.      [\fB, hashes\fR]
  21.      [\fB, join =\fR join_proc ]
  22.      [\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ]
  23.     \fB)\fR
  24. .\" \fB"arg is ("
  25. .\" type [
  26. .\" \fB,
  27. .\" type ]
  28. .\" \fB)
  29. .)l
  30. .uh DESCRIPTION
  31. .lp
  32. This command defines a new user operator,
  33. .i "operator_name" .
  34. The user who defines an operator becomes its owner.
  35. .lp
  36. The name of the operator,
  37. .i operator_name ,
  38. can be composed of symbols only. 
  39. Also, the
  40. .i func_name
  41. procedure
  42. must have been previously defined using 
  43. .b "define function"
  44. and must have one
  45. or two arguments.
  46. The types of the arguments for the operator 
  47. and the type of the
  48. answer are as defined by the function.
  49. .b Precedence
  50. refers to the order that multiple instances of the same
  51. operator are evaluated.
  52. .\" what does this number mean and what is its range?
  53. The next several fields are primarily for the use of the query optimizer.
  54. .lp
  55. The
  56. .b associativity
  57. value is used to indicate how an expression containing
  58. this operator should be evaluated when precedence
  59. and explicit grouping are insufficient to produce
  60. a complete order of evaluation.
  61. .b Left
  62. and
  63. .b right
  64. indicate that expressions containing
  65. the operator are to be evaluated from left to right or
  66. from right to left, respectively.
  67. .b None
  68. means that it is an error for
  69. this operator to be used without
  70. explicit grouping when there is ambiguity.
  71. And
  72. .b any ,
  73. the default,
  74. indicates that the optimizer may choose to evaluate
  75. an expression which contains this operator arbitrarily.
  76. .lp
  77. .\" that multiple instances of the 
  78. .\" operator must be be evaluated
  79. .\" For example, consider the area-intersection operator,
  80. .\" .q A,
  81. .\" and the following expression:
  82. .\" .(l
  83. .\" MYBOXES2.description A \*(lq0,0,1,1\*(rq A MYBOXES.description
  84. .\" .)l
  85. .\" .in .5i
  86. .\" The associativity flag indicates that
  87. .\" .(l
  88. .\" (MYBOXES2.description A \*(lq0,0,1,1\*(rq) A MYBOXES.description
  89. .\" .)l
  90. .\" .in .5i
  91. .\" is the same as
  92. .\" .(l
  93. .\" MYBOXES2.description A (\*(lq0,0,1,1\*(rq A MYBOXES.description).
  94. .\" .)l
  95. The commutator operator is present so that \*(PP can reverse
  96. the order of the operands if it wishes.
  97. For example, the operator area-less-than, >>>,
  98. would have a commutator operator, area-greater-than, <<<.
  99. Suppose that an operator, area-equal, ===, exists, as well as an area
  100. not equal, !==.  Hence, the query optimizer could freely convert:
  101. .(l
  102. .ft C
  103. "0,0,1,1"::box >>> MYBOXES.description
  104. .ft
  105. .)l
  106. .in .5i
  107. to
  108. .(l
  109. .ft C
  110. MYBOXES.description <<< "0,0,1,1"::box
  111. .ft
  112. .)l
  113. .in .5i
  114. This allows the execution code to always use the latter representation
  115. and simplifies the query optimizer somewhat.
  116. .sp
  117. The negator operator allows the query optimizer to convert
  118. .(l
  119. .ft C
  120. not MYBOXES.description === "0,0,1,1"::box
  121. .ft
  122. .)l
  123. .in .5i
  124. to
  125. .(l
  126. .ft C
  127. MYBOXES.description !== "0,0,1,1"::box
  128. .ft
  129. .)l
  130. .in .5i
  131. .sp
  132. If a commutator operator name is supplied,
  133. \*(PP searches for it in the catalog.
  134. If it is found and it does not yet have a commutator itself,
  135. then the commutator's entry is updated to have the
  136. current (new) operator as its commutator.
  137. This applies to the negator,
  138. as well.
  139. .sp
  140. This is to allow the definition of two operators that are the
  141. commutators or the negators of each other.
  142. The first operator should be defined without a commutator or
  143. negator (as appropriate).
  144. When the second operator is defined,
  145. name the first as the commutator or negator.
  146. The first will be updated as a side effect.
  147. .sp
  148. The next two specifications are present to support the query optimizer
  149. in performing joins.
  150. \*(PP can always evaluate a
  151. join (i.e., processing a clause with two tuple variables separated by
  152. an operator that returns a boolean) by iterative substitution [WONG76].  
  153. In addition,
  154. \*(PP is planning on implementing a hash-join
  155. algorithm along the lines of [SHAP86]; however, it must know whether this
  156. strategy is applicable.  For example, a hash-join algorithm is usable for
  157. a clause of the form:
  158. .(l
  159. .ft C
  160. MYBOXES.description === MYBOXES2.description
  161. .ft
  162. .)l
  163. .in .5i
  164. but not for a clause of the form:
  165. .(l
  166. .ft C
  167. MYBOXES.description <<< MYBOXES2.description.
  168. .ft
  169. .)l
  170. .in .5i
  171. The
  172. .i hashes
  173. flag gives the needed information to the query optimizer
  174. concerning whether a hash join strategy is usable for the operator
  175. in question.  
  176. .sp
  177. Similarly, the two sort
  178. operators indicate to the query optimizer whether merge-sort is a
  179. usable join strategy
  180. and what operators should be used to
  181. sort the two operand classes.
  182. For the === clause above, the optimizer must
  183. sort both relations using the operator, <<<.
  184. On the other hand, merge-sort is not usable with the clause: 
  185. .(l
  186. .ft C
  187. MYBOXES.description <<< MYBOXES2.description
  188. .ft
  189. .)l
  190. If other join strategies are found to be practical,
  191. \*(PP will change
  192. the optimizer and run-time system to use them and 
  193. will require additional specification
  194. when an operator is defined. 
  195. Fortunately, the research community invents new join strategies infrequently,
  196. and the added generality of user-defined join strategies was not felt to
  197. be worth the complexity involved.
  198. .lp
  199. The last two pieces of the specification are present so the query 
  200. optimizer can estimate result sizes.  If a clause of the form:
  201. .(l
  202. .ft C
  203. MYBOXES.description <<< "0,0,1,1"::box
  204. .ft
  205. .)l
  206. .in .5i
  207. is present in the qualification, 
  208. then \*(PP may have to 
  209. estimate the fraction of the instances in MYBOXES
  210. that satisfy the clause.  The function res_proc must
  211. be a registered function (meaning it is already defined using
  212. .b "define function"
  213. )
  214. which accepts one argument of the correct
  215. data type and returns a floating point number.  The query optimizer
  216. simply calls this function, passing the parameter
  217. .ft C
  218. "0,0,1,1"
  219. .ft
  220. and multiplies the result by the relation size to get the desired expected
  221. number of instances.
  222. .sp
  223. Similarly, when the operands of the operator both contain instance variables,
  224. the query optimizer must estimate the size of the resulting join.
  225. The function join_proc will return another
  226. floating point number which will be multiplied by the cardinalities of the two
  227. classes involved to compute the desired expected result size.
  228. .sp
  229. The difference between the function
  230. .(l
  231. .ft C
  232. my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
  233. .ft
  234. .)l
  235. .in .5i
  236. and the operator
  237. .(l
  238. .ft C
  239. MYBOXES.description === "0,0,1,1"::box
  240. .ft
  241. .)l
  242. .in .5i
  243. is that \*(PP attempts to optimize operators and can decide to 
  244. use an index to restrict the search space when operators are involved.
  245. However, there is no attempt to optimize functions, and they are performed
  246. by brute force.  Moreover, functions can have any number of arguments
  247. while operators are restricted to one or two.
  248. .sp
  249. .(b
  250. .uh EXAMPLE
  251. .lp
  252. .nf
  253. .ft C
  254. /* The following command defines a new operator, */
  255. /* area-equality, for the BOX data type.         */
  256.  
  257. define operator === (
  258.     arg1 = box,
  259.     arg2 = box,
  260.     procedure = area_equal_procedure,
  261.     precedence = 30,
  262.     associativity = left,
  263.     commutator = ===,
  264.     negator = !==,
  265.     restrict = area_restriction_procedure,
  266.     hashes,
  267.     join = area-join-procedure,
  268.     sort = <<<, <<<)
  269. .\"    arg is (box, box)
  270. .ft
  271. .)b
  272. .uh "SEE ALSO"
  273. .lp
  274. remove operator(commands),
  275. define function(commands).
  276. .uh BUGS
  277. .lp
  278. Operator names cannot be composed of alphabetic characters in Version \*(PV.
  279. .lp
  280. Operator precedence and associativity are not implemented in Version \*(PV.
  281.